<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>geosnap.harmonize.harmonize &#8212; geosnap v0.3.1 Manual</title>
    <link rel="stylesheet" href="../../../_static/bootstrap-sphinx.css" type="text/css" />
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" type="text/css" href="../../../_static/pysal-styles.css" />
    <script id="documentation_options" data-url_root="../../../" src="../../../_static/documentation_options.js"></script>
    <script src="../../../_static/jquery.js"></script>
    <script src="../../../_static/underscore.js"></script>
    <script src="../../../_static/doctools.js"></script>
    <script src="../../../_static/language_data.js"></script>
    <link rel="shortcut icon" href="../../../_static/geosnap.ico"/>
    <link rel="index" title="Index" href="../../../genindex.html" />
    <link rel="search" title="Search" href="../../../search.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="../../../_static/js/jquery-1.11.0.min.js "></script>
<script type="text/javascript" src="../../../_static/js/jquery-fix.js "></script>
<script type="text/javascript" src="../../../_static/bootstrap-3.3.7/js/bootstrap.min.js "></script>
<script type="text/javascript" src="../../../_static/bootstrap-sphinx.js "></script>

  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="../../../index.html"><span><img src="../../../_static/geosnap.svg"></span>
          geosnap</a>
        <span class="navbar-text navbar-version pull-left"><b>0.3.1</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="../../../installation.html">Installation</a></li>
                <li><a href="../../../api.html">API</a></li>
                <li><a href="../../../data.html">Data</a></li>
                <li><a href="https://spatialucr.github.io/geosnap-guide/">User Guide</a></li>
                <li><a href="../../../references.html">References</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="../../../index.html">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><p class="caption"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../installation.html">Installation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../../installation.html#installing-a-released-version">Installing a released version</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../installation.html#installing-development-version">Installing development version</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../api.html">API</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../../api.html#io-module">IO Module</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../api.html#the-community-class">The Community Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../api.html#analyze-module">Analyze Module</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../api.html#harmonize-module">Harmonize Module</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../api.html#visualize-module">Visualize Module</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../references.html">References</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../data.html">Data</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../../../data.html#tabular-data">Tabular Data</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../data.html#geo-data">Geo Data</a></li>
</ul>
</li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"></ul>
</li>
              
            
            
            
            
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="../../../search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <h1>Source code for geosnap.harmonize.harmonize</h1><div class="highlight"><pre>
<span></span><span class="sd">&quot;&quot;&quot;Use spatial interpolation to standardize neighborhood boundaries over time.&quot;&quot;&quot;</span>

<span class="kn">import</span> <span class="nn">geopandas</span> <span class="k">as</span> <span class="nn">gpd</span>
<span class="kn">import</span> <span class="nn">pandas</span> <span class="k">as</span> <span class="nn">pd</span>
<span class="kn">from</span> <span class="nn">tobler.area_weighted</span> <span class="kn">import</span> <span class="p">(</span>
    <span class="n">area_interpolate</span><span class="p">,</span>
    <span class="n">area_tables_raster</span><span class="p">,</span>
<span class="p">)</span>
<span class="kn">from</span> <span class="nn">tobler.area_weighted</span> <span class="kn">import</span> <span class="n">_slow_area_interpolate</span>
<span class="kn">from</span> <span class="nn">tobler.util.util</span> <span class="kn">import</span> <span class="n">_check_presence_of_crs</span>


<div class="viewcode-block" id="harmonize"><a class="viewcode-back" href="../../../generated/geosnap.harmonize.harmonize.html#geosnap.harmonize.harmonize">[docs]</a><span class="k">def</span> <span class="nf">harmonize</span><span class="p">(</span>
    <span class="n">raw_community</span><span class="p">,</span>
    <span class="n">target_year</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
    <span class="n">weights_method</span><span class="o">=</span><span class="s2">&quot;area&quot;</span><span class="p">,</span>
    <span class="n">extensive_variables</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
    <span class="n">intensive_variables</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
    <span class="n">allocate_total</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
    <span class="n">raster</span><span class="o">=</span><span class="s2">&quot;nlcd_2011&quot;</span><span class="p">,</span>
    <span class="n">codes</span><span class="o">=</span><span class="p">[</span><span class="mi">21</span><span class="p">,</span> <span class="mi">22</span><span class="p">,</span> <span class="mi">23</span><span class="p">,</span> <span class="mi">24</span><span class="p">],</span>
    <span class="n">force_crs_match</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
    <span class="n">index</span><span class="o">=</span><span class="s2">&quot;geoid&quot;</span><span class="p">,</span>
    <span class="n">time_col</span><span class="o">=</span><span class="s2">&quot;year&quot;</span><span class="p">,</span>
<span class="p">):</span>
    <span class="sa">r</span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Use spatial interpolation to standardize neighborhood boundaries over time.</span>

<span class="sd">    Parameters</span>
<span class="sd">    ----------</span>
<span class="sd">    raw_community : list of geopandas.GeoDataFrames</span>
<span class="sd">        Multiple GeoDataFrames given by a list (see (1) in Notes).</span>

<span class="sd">    target_year : string</span>
<span class="sd">        The target year that represents the bondaries of all datasets generated</span>
<span class="sd">        in the harmonization. Could be, for example &#39;2010&#39;.</span>

<span class="sd">    weights_method : string</span>
<span class="sd">        The method that the harmonization will be conducted. This can be set to:</span>
<span class="sd">            * &quot;area&quot;                          : harmonization according to area weights.</span>
<span class="sd">            * &quot;land_type_area&quot;                : harmonization according to the Land Types considered &#39;populated&#39; areas.</span>
<span class="sd">            * &quot;land_type_Poisson_regression&quot;  : NOT YET INTRODUCED.</span>
<span class="sd">            * &quot;land_type_Gaussian_regression&quot; : NOT YET INTRODUCED.</span>

<span class="sd">    extensive_variables : list</span>
<span class="sd">        The names of variables in each dataset of raw_community that contains</span>
<span class="sd">        extensive variables to be harmonized (see (2) in Notes).</span>

<span class="sd">    intensive_variables : list</span>
<span class="sd">        The names of variables in each dataset of raw_community that contains</span>
<span class="sd">        intensive variables to be harmonized (see (2) in Notes).</span>

<span class="sd">    allocate_total : boolean</span>
<span class="sd">        True if total value of source area should be allocated.</span>
<span class="sd">        False if denominator is area of i. Note that the two cases</span>
<span class="sd">        would be identical when the area of the source polygon is</span>
<span class="sd">        exhausted by intersections. See (3) in Notes for more details.</span>

<span class="sd">    raster : str</span>
<span class="sd">        the path to the associated raster image that has the types of</span>
<span class="sd">        each pixel in the spatial context.</span>
<span class="sd">        Only taken into consideration for harmonization raster based.</span>

<span class="sd">    codes : an integer list of codes values that should be considered as</span>
<span class="sd">        &#39;populated&#39;. Since this draw inspiration using the National Land Cover</span>
<span class="sd">        Database (NLCD), the default is 21 (Developed, Open Space),</span>
<span class="sd">        22 (Developed, Low Intensity), 23 (Developed, Medium Intensity) and</span>
<span class="sd">        24 (Developed, High Intensity). The description of each code can be</span>
<span class="sd">        found here:</span>
<span class="sd">        https://www.mrlc.gov/sites/default/files/metadata/landcover.html</span>
<span class="sd">        Only taken into consideration for harmonization raster based.</span>

<span class="sd">    force_crs_match : bool. Default is True.</span>
<span class="sd">        Wheter the Coordinate Reference System (CRS) of the polygon will be</span>
<span class="sd">        reprojected to the CRS of the raster file. It is recommended to</span>
<span class="sd">        leave this argument True.</span>
<span class="sd">        Only taken into consideration for harmonization raster based.</span>


<span class="sd">    Notes</span>
<span class="sd">    -----</span>
<span class="sd">    1) Each GeoDataFrame of raw_community is assumed to have a &#39;year&#39; column</span>
<span class="sd">       Also, all GeoDataFrames must have the same Coordinate Reference System (CRS).</span>

<span class="sd">    2) A quick explanation of extensive and intensive variables can be found</span>
<span class="sd">    here: http://ibis.geog.ubc.ca/courses/geob370/notes/intensive_extensive.htm</span>

<span class="sd">    3) For an extensive variable, the estimate at target polygon j (default case) is:</span>

<span class="sd">        v_j = \sum_i v_i w_{i,j}</span>

<span class="sd">        w_{i,j} = a_{i,j} / \sum_k a_{i,k}</span>

<span class="sd">        If the area of the source polygon is not exhausted by intersections with</span>
<span class="sd">        target polygons and there is reason to not allocate the complete value of</span>
<span class="sd">        an extensive attribute, then setting allocate_total=False will use the</span>
<span class="sd">        following weights:</span>

<span class="sd">        v_j = \sum_i v_i w_{i,j}</span>

<span class="sd">        w_{i,j} = a_{i,j} / a_i</span>

<span class="sd">        where a_i is the total area of source polygon i.</span>

<span class="sd">        For an intensive variable, the estimate at target polygon j is:</span>

<span class="sd">        v_j = \sum_i v_i w_{i,j}</span>

<span class="sd">        w_{i,j} = a_{i,j} / \sum_k a_{k,j}</span>

<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">if</span> <span class="n">extensive_variables</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">intensive_variables</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
            <span class="s2">&quot;You must pass a set of extensive and/or intensive variables to interpolate&quot;</span>
        <span class="p">)</span>

    <span class="n">_check_presence_of_crs</span><span class="p">(</span><span class="n">raw_community</span><span class="p">)</span>
    <span class="n">dfs</span> <span class="o">=</span> <span class="n">raw_community</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
    <span class="n">times</span> <span class="o">=</span> <span class="n">dfs</span><span class="p">[</span><span class="n">time_col</span><span class="p">]</span><span class="o">.</span><span class="n">unique</span><span class="p">()</span>

    <span class="n">target_df</span> <span class="o">=</span> <span class="n">dfs</span><span class="p">[</span><span class="n">dfs</span><span class="p">[</span><span class="n">time_col</span><span class="p">]</span> <span class="o">==</span> <span class="n">target_year</span><span class="p">]</span><span class="o">.</span><span class="n">reset_index</span><span class="p">()</span>

    <span class="n">interpolated_dfs</span> <span class="o">=</span> <span class="p">{}</span>
    <span class="n">interpolated_dfs</span><span class="p">[</span><span class="n">target_year</span><span class="p">]</span> <span class="o">=</span> <span class="n">target_df</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>

    <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">times</span><span class="p">:</span>
        <span class="n">source_df</span> <span class="o">=</span> <span class="n">dfs</span><span class="p">[</span><span class="n">dfs</span><span class="p">[</span><span class="n">time_col</span><span class="p">]</span> <span class="o">==</span> <span class="n">i</span><span class="p">]</span>

        <span class="k">if</span> <span class="n">weights_method</span> <span class="o">==</span> <span class="s2">&quot;area&quot;</span><span class="p">:</span>

            <span class="c1"># In area_interpolate, the resulting variable has same lenght as target_df</span>
            <span class="n">interpolation</span> <span class="o">=</span> <span class="n">area_interpolate</span><span class="p">(</span>
                <span class="n">source_df</span><span class="p">,</span>
                <span class="n">target_df</span><span class="o">.</span><span class="n">copy</span><span class="p">(),</span>
                <span class="n">extensive_variables</span><span class="o">=</span><span class="n">extensive_variables</span><span class="p">,</span>
                <span class="n">intensive_variables</span><span class="o">=</span><span class="n">intensive_variables</span><span class="p">,</span>
                <span class="n">allocate_total</span><span class="o">=</span><span class="n">allocate_total</span><span class="p">,</span>
            <span class="p">)</span>

        <span class="k">elif</span> <span class="n">weights_method</span> <span class="o">==</span> <span class="s2">&quot;land_type_area&quot;</span><span class="p">:</span>
            <span class="k">try</span><span class="p">:</span>

                <span class="n">area_tables_raster_fitted</span> <span class="o">=</span> <span class="n">area_tables_raster</span><span class="p">(</span>
                    <span class="n">source_df</span><span class="p">,</span>
                    <span class="n">target_df</span><span class="o">.</span><span class="n">copy</span><span class="p">(),</span>
                    <span class="n">raster_path</span><span class="o">=</span><span class="n">raster</span><span class="p">,</span>
                    <span class="n">codes</span><span class="o">=</span><span class="n">codes</span><span class="p">,</span>
                    <span class="n">force_crs_match</span><span class="o">=</span><span class="n">force_crs_match</span><span class="p">,</span>
                <span class="p">)</span>

                <span class="c1"># In area_interpolate, the resulting variable has same lenght as target_df</span>
                <span class="n">interpolation</span> <span class="o">=</span> <span class="n">_slow_area_interpolate</span><span class="p">(</span>
                    <span class="n">source_df</span><span class="p">,</span>
                    <span class="n">target_df</span><span class="o">.</span><span class="n">copy</span><span class="p">(),</span>
                    <span class="n">extensive_variables</span><span class="o">=</span><span class="n">extensive_variables</span><span class="p">,</span>
                    <span class="n">intensive_variables</span><span class="o">=</span><span class="n">intensive_variables</span><span class="p">,</span>
                    <span class="n">allocate_total</span><span class="o">=</span><span class="n">allocate_total</span><span class="p">,</span>
                    <span class="n">tables</span><span class="o">=</span><span class="n">area_tables_raster_fitted</span><span class="p">,</span>
                <span class="p">)</span>
            <span class="k">except</span> <span class="ne">IOError</span><span class="p">:</span>
                <span class="k">raise</span> <span class="ne">IOError</span><span class="p">(</span>
                    <span class="s2">&quot;You must have NLCD raster data installed locally to use the&quot;</span>
                    <span class="s2">&quot;`land_type_area` method. You can install it using the&quot;</span>
                    <span class="s2">&quot;`tobler.data.store_rasters()` function from the `tobler` package&quot;</span>
                <span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;weights_method must of one of [&quot;area&quot;, &quot;land_type_area&quot;]&#39;</span><span class="p">)</span>

        <span class="n">profiles</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">if</span> <span class="n">extensive_variables</span><span class="p">:</span>
            <span class="n">profile</span> <span class="o">=</span> <span class="n">interpolation</span><span class="p">[</span><span class="n">extensive_variables</span><span class="p">]</span>
            <span class="n">profiles</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">profile</span><span class="p">)</span>

        <span class="k">if</span> <span class="n">intensive_variables</span><span class="p">:</span>
            <span class="n">profile</span> <span class="o">=</span> <span class="n">interpolation</span><span class="p">[</span><span class="n">intensive_variables</span><span class="p">]</span>
            <span class="n">profiles</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">profile</span><span class="p">)</span>

        <span class="n">profile</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">concat</span><span class="p">(</span><span class="n">profiles</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
        <span class="n">profile</span><span class="p">[</span><span class="s2">&quot;geometry&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">target_df</span><span class="p">[</span><span class="s2">&quot;geometry&quot;</span><span class="p">]</span>
        <span class="n">profile</span><span class="p">[</span><span class="n">index</span><span class="p">]</span> <span class="o">=</span> <span class="n">target_df</span><span class="p">[</span><span class="n">index</span><span class="p">]</span>
        <span class="n">profile</span><span class="p">[</span><span class="n">time_col</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span>

        <span class="n">interpolated_dfs</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">profile</span>

    <span class="n">harmonized_df</span> <span class="o">=</span> <span class="n">gpd</span><span class="o">.</span><span class="n">GeoDataFrame</span><span class="p">(</span>
        <span class="n">pd</span><span class="o">.</span><span class="n">concat</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">interpolated_dfs</span><span class="o">.</span><span class="n">values</span><span class="p">()),</span> <span class="n">sort</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
    <span class="p">)</span>

    <span class="k">return</span> <span class="n">harmonized_df</span></div>
</pre></div>

    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
        <br/>
        
      
    </p>
    <p>
        &copy; Copyright 2020, geosnap developers.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.4.<br/>
    </p>
  </div>
</footer>
  </body>
</html>